Cache-control request directive stale-if-error is missing documentation

[gmartenscb]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control

What specific section or headline is this issue about?

Request directives: stale-if-error

What information was incorrect, unhelpful, or incomplete?

There is no documentation or mention of the stale-if-error request directive, under the Request directive section.
It is mentioned in the table at the top, but not in its dedicated section.

What did you expect to see?

The directive being listed and explained as a request directive
Perhaps something like:

The stale-if-error request directive indicates that caches can reuse a stale response when the origin server generates an error, or when the error is generated locally. Here, an error is considered any response with a status code of 500, 502, 503, or 504.

Do you have any supporting links, references, or citations?

No response

Do you have anything more you want to share?

No response

MDN metadata

Page report details

• Folder: en-us/web/http/reference/headers/cache-control
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/http/reference/headers/cache-control/index.md
• Last commit: ee756fd
• Document last modified: 2025-05-23T16:30:28.000Z

[gmartenscb]

Moreover, the example I gave above is copy of the response directive, but adjusted to the wording used for request directives. The example:

The stale-if-error request directive indicates that caches can reuse a stale response when the origin server generates an error, or when the error is generated locally. Here, an error is considered any response with a status code of 500, 502, 503, or 504.

Apart from the fact that the wording between request and response directive is quite inconsistent, I also think the instructions are quite unclear. The directive has a clear =N (similar to max-age=N), which is never mentioned in the documentation.

On top of that, the max-stale directive has clear instructions on what to do if no N is provided:

If no N value is specified, the client will accept a stale response of any age.

However, for the stale-if-error directive nothing in regards to this is mentioned or specified.
Does this mean a number is always mandatory? Can it be omitted and treated as "a stale response of any age"?
And what if the number is zero, negative or not an integer? This is specified for the max-age directive:

If the max-age value is negative (for example, -1) or isn't an integer (for example, 3599.99), then the caching behavior is unspecified. Caches are encouraged to treat the value as if it were 0.

[hamishwillee]

As I understand it, a browser that supports this directive in a request would be indicating it's interest in specifically receiving stale content on error for a particular origin from any intermediate server.
This is subtly different from the the response, which is the server saying that is will allow its content to be used by an intermediate server on error.

MDN generally documents things that have browser support - in this case no browsers have support explicit support for stale-if-error so it isn't supported "from a browser compatibility or MDN point of view".

That said, this is a bit confusing, and we should probably make this explict.

Would you like to create a PR to add the section saying "this is is what it is for, but it is not yet supported in browsers"?